Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

Now refine the solution by adding more detailed descriptions of the steps you need to take. Indent to show that a line is part of the previous line.

Again, the description should not invoke actual Visual Basic commands, though it will become increasingly obvious which commands are needed. For example, for one line, you may know that you will need to use a For loop.

Continue refining the description until it starts to look like an English form of Visual Basic.

Sort an array of numbers.
    Validate the parameters.
    Check that the array contains between 10 and 1000 entries.
    (Anything outside this range may indicate a bug)

    For each position in the array:
        Find the smallest item not yet positioned:
        Start with the item currently in the
            position we are considering.

        For each entry after this one:
            If an entry is smaller than the smallest so far:
                Save its value and index.

        Swap the smallest item into the position we are considering.

    Verify the solution.
    For each item after the first:
        Check that it is at least as big as the previous item.

Now put apostrophes to the left of each line of the description to turn them into comments.

‘ Sort an array of numbers.
    ‘ Validate the parameters.
    ‘ Check that the array contains between 10 and 1000 entries.
    ‘ (Anything outside this range may indicate a bug)

    ‘ For each position in the array:
        ‘ Find the smallest item not yet positioned:
        ‘ Start with the item currently in the
        ‘     position we are considering.

        ‘ For each entry after this one:
            ‘ If an entry is smaller than the smallest so far:
                ‘ Save its value and index.

        ‘ Swap the smallest item into the position we are considering.

    ‘ Verify the solution.
    ‘ For each item after the first:
        ‘ Check that it is at least as big as the previous item.

Next, insert the routine’s declaration with any required parameters after the top-level description. Insert other Visual Basic code to implement the functionality described in the comments. The code should echo the comment before it. Add blank lines as needed to make the code easier to read.

The following code uses an #If statement to control program execution during design time and in the final compiled program. In this case, the compiler symbol DEBUG_MODE is defined during design time to verify the routine’s solution. Before compiling the final program, the developer sets DEBUG_MODE to False so this code will be removed from the final version. This technique and several others for verifying program correctness are discussed in Chapter 5, “Exposing Bugs.”

‘ Sort an array of numbers.
Public Sub SelectionSort(ByRef numbers() As Integer)
    ‘ Validate the parameters.
    ‘ Check that the array contains between 10 and 1000 entries.
    ‘ (Anything outside this range may indicate a bug)
    Debug.Assert (UBound(numbers) - LBound(numbers) + 1) >= 10
    Debug.Assert (UBound(numbers) - LBound(numbers) + 1) <= 1000

    ‘ For each position in the array:
    For i = LBound(numbers) To UBound(numbers)
        ‘ Find the smallest item not yet positioned:
        ‘ Start with the item currently in the
        ‘ position we are considering.
        smallest_value = numbers(i)
        smallest_index = i

        ‘ For each entry after this one:
        For j = i + 1 To UBound(numbers)
            ‘ If an entry is smaller than the smallest so far:
            If numbers(j) < smallest_value Then
                ‘ Save its value and index.
                smallest_value = numbers(j)
                smallest_index = j
            End If
        Next j

        ‘ Swap the smallest item into the position we are considering.
        numbers(smallest_index) = numbers(i)
        numbers(i) = smallest_value
    Next i

    ‘ Verify the solution.
    #If DEBUG_MODE Then
        ‘ For each item after the first:
        For i = LBound(numbers) + 1 To UBound(numbers)
            ‘ Check that it is at least as big as the previous item.
            If numbers(i) < numbers(i - 1) Then Stop
        Next i
    #End If
End Sub

Now look through the code and see what variables it uses. Declare them at the top of the routine. Explicitly declare each variable on a separate line.

‘ Sort an array of numbers.
Public Sub SelectionSort(ByRef numbers() As Integer)
Dim i As Integer
Dim j As IntegerDim smallest_value As Integer
Dim smallest_index As Integer

    ‘ Validate the parameters.
    ‘ Check that the array contains between 10 and 1000 entries.
    ‘ (Anything outside this range may indicate a bug)
    Debug.Assert (UBound(numbers) - LBound(numbers) + 1) >= 10
    Debug.Assert (UBound(numbers) - LBound(numbers) + 1) <= 1000

    ‘ For each position in the array:
    For i = LBound(numbers) To UBound(numbers)
        ‘ Find the smallest item not yet positioned:
        ‘ Start with the item currently in the
        ‘ position we are considering.
        smallest_value = numbers(i)
        smallest_index = i

        ‘ For each entry after this one:
        For j = i + 1 To UBound(numbers)
            ‘ If an entry is smaller than the smallest so far:
            If numbers(j) < smallest_value Then
                ‘ Save its value and index.
                smallest_value = numbers(j)
                smallest_index = j
            End If
        Next j

        ‘ Swap the smallest item into the position we are considering.
        numbers(smallest_index) = numbers(i)
        numbers(i) = smallest_value
    Next i

    ‘ Verify the solution.
    #If DEBUG_MODE Then

        ‘ For each item after the first:
        For i = LBound(numbers) + 1 To UBound(numbers)
            ‘ Check that it is at least as big as the previous item.
            If numbers(i) < numbers(i - 1) Then Stop
        Next i
    #End If
End Sub

Finally, run the subroutine and test it thoroughly. Step through the code in the debugger to make sure it all runs. In particular, check that the verification code at the end actually runs. If the DEBUG_MODE compiler constant is not defined, this code will be skipped.

You may feel that all these extra steps waste time. Actually, they are steps you need to perform anyway. They are just being accomplished in a different order. You need to think the solution through completely one way or another. By refining the solution in English instead of Visual Basic, you can concentrate on the design without being distracted by Visual Basic syntax.

When you have finished refining the English version of the routine, you will have a conceptually integrated design that you can translate into Visual Basic quickly and easily. At this point, translation is almost purely mechanical. You have already debugged the design so you will not need to spend as much time writing and rewriting the code to make the routine work. The time you spend designing the routine in English saves you time while coding.

When all this is done, you have a completely commented subroutine. You can add a few extra comments to clarify any confusing issues, but the description you originally built should explain most of the routine. The time you spend in design not only saves you coding time, but it also saves you much of the time you would have spent commenting the code later.